# People counting device
***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***
---
This project is a lightweight people counting solution developed based on the Quectel Pi M2 smart single-board computer. It integrates technologies such as object detection, object tracking, and person re-identification (ReID), and provides the following core features:
- **Real-time human detection**: Real-time identification of human targets in video streams.
- **Stable object tracking**: High-precision target tracking using the ByteTrack algorithm.
- **Intelligent deduplication statistics**: Personnel identity deduplication based on ReID features.
- **Multi-source video support**: Compatible with USB cameras, IP cameras, and local video files.
- **Multi-dimensional statistics**: Provide real-time count, cumulative deduplicated count, and entry/exit direction statistics.
```{image} images/image_E7U3b4Ng1o1CcDxCxcqcyzqSn9e.webp
:width: 1070px
:height: 587px
```
# Development resources summary
## Development accessories list
```{note}
The following accessories list is for reference only. The actual development environment can be adjusted according to requirements. For example, when you develop via SSH remote connection, the display and USB hub can be omitted. Select a camera according to actual requirements.
```
| **Accessory** | **Quantity** | **Specifications** |
| --- | --- | --- |
| Quectel Pi M2 smart single-board computer | 1 | -) |
| HDMI Type-A Male Cable | 1 | HDMI 2.0; cable length 1 m; connectors: HDMI-A (male) to HDMI-A (male) |
| Ethernet cable | 1 | Length: 1 m; Transmission rate: Gigabit. |
| Network camera | 1 | [Tenda indoor home surveillance camera]() |
| USB Camera Module | 1 | [UGREEN HD USB Camera with Microphone (2K 4MP Auto Focus)]() |
| Display | 1 | 24-inch HDMI monitor |
## Physical reference of accessories
```{image} images/image_EjBZbBx2Zo7SRMxzbBscZuy8njb.webp
:width: 973px
:height: 621px
:align: center
```
# Quick start
## Development preparation
The Quectel Pi M2 smart single-board computer comes with the **Debian 13** system image pre-installed. Therefore, you do not need to flash the system image again and follow the steps below.
## Hardware connection
Complete all hardware connections as described below. The step numbers match the labels in the interface diagram.
```{image} images/image_IqmNbyBwHopzNoxrdPScgLXKnrf.webp
:width: 629px
:height: 437px
:align: center
```
1. **Display connection**: Connect one end of the Micro HDMI cable to the Micro HDMI port on the Quectel Pi M2 smart single-board computer and the other end to the HDMI port on the monitor.
2. **Network connection**: Ensure that the router is connected to the internet. Connect one end of the Ethernet cable to the Gigabit Ethernet port on the Quectel Pi M2 smart single-board computer and the other end to the Ethernet port on the router.
3. **Input device connection**: Connect the USB keyboard, mouse, and OV5693 USB camera module to the USB ports on the docking station. Then connect the docking station to a USB port on the Quectel Pi M2 smart single-board computer. If you are using wireless input devices, connect the wireless receiver to a USB port on the docking station.
4. **Power connection**: Connect the USB-A end of the USB-A power cable to the output of the power adapter and the USB-C end to the power input on the smart single-board computer (usually labeled **POWER IN**).
5. **Network camera connection**: Connect the network camera to a power source using its supplied power cable, and ensure that it is on the same local area network as the Quectel Pi M2 smart single-board computer.
## Model preparation
### Object detection model
The project supports the YOLOv8n model, which is in the *src/* directory.
```{note}
All model files are included in the project and located in the *src/* directory. No additional download is required.
```
### Person re-identification model
- **ReID model**: *osnet_x0_25_market1501.onnx* (located in the *src/* directory).
- **Input size**: 256 × 128 (width × height).
- **Feature dimension**: 512-dimensional normalized feature vector.
```{note}
The ReID model must be fine-tuned on a ReID dataset such as Market1501. Do not use an ImageNet-pretrained model directly.
```
## Statistics logic explanation
### Count types
1. **Current count**: The number of active targets detected in the current video frame.
2. **Total count**: The historical cumulative deduplicated count based on unique *track_id* values.
3. **In/Out count**: Personnel entry/exit direction statistics based on a virtual detection line.
### Counting principles
- **Current count**: Directly count the active tracked targets in the current frame.
- **Total count**: Each newly generated *track_id* corresponds to a unique person identifier, ensuring accurate cumulative statistics.
- **In/Out count**: Determine the target movement direction using a virtual detection line (the default is the horizontal line at the center of the screen):
- **In**: The target moves downward (the Y coordinate increases).
- **Out**: The target moves upward (the Y coordinate decreases).
- Determine the crossing direction based on the historical trajectory of the target's center point.
- Count each *track_id* only once, when it first crosses the virtual line, to avoid duplicate counting.
### Custom virtual line
The current version supports customizing the position and direction of the virtual detection line:
- **Horizontal detection line**: direction='horizontal', line_position=specified Y coordinate
- **Vertical detection line**: direction='vertical', line_position=specified X coordinate
## Deployment recommendations
### Camera installation position
- Install the camera directly above or to the side of the passage. Cover the entire area through which targets pass so that each person remains visible while entering or leaving the counting area.
- The recommended installation height is 2.2–3.5 m. For ceiling-mounted cameras, point the lens as vertically downward as possible. If the camera is installed too low, occlusion and truncation of the lower body may occur.
- Avoid glass, reflective curtain walls, and strong backlighting. Prevent large reflections or obstructions in front of the lens.
- Do not place large pillars, shelves, or plants near the counting line, as they may temporarily block targets.
### Orientation and angle recommendations
- Prefer a view that is slightly downward from the front. A pitch angle of approximately 15°–45° is recommended. A view that is too level increases occlusion, while a view that is too steep may compress people into small targets.
- For side-mounted cameras, keep the direction of human movement at a small angle to the optical axis to avoid incomplete target contours caused by side views at the edge of the image.
- Keep the counting line near the center of the field of view, maintain a stable camera angle, and avoid frequent shaking or rotation.
### Lighting recommendations
- Use uniform, soft, front-facing illumination. Set the light level high enough to identify human shapes clearly while avoiding obvious shadows.
- Avoid backlighting, strong side lighting, and direct sunlight. Do not allow sunlight to shine directly into the lens, as this affects detection and tracking.
- For nighttime use, add a fill light or infrared light and keep the illumination stable. Avoid flicker and obvious brightness fluctuations.
- When the video feed is too dark, has excessive contrast, or contains large areas of overexposure, the algorithm is more likely to miss detections or produce false detections.
### Effects of deployment method on algorithm performance
- **USB camera**: Deployed locally on the device, with low latency and stable images; generally more suitable for real-time counting and on-site debugging.
- **IP camera**: More affected by network bandwidth, encoding format, packet loss, and image compression. Detection and tracking performance decreases when the resolution or bit rate is too low or the frame rate is unstable.
- **Local video file**: Suitable for algorithm validation and offline testing. Compared with real-site deployment, the file's encoding, frame rate, and playback method may affect the results, so it cannot fully represent a real-time camera scenario.
## Project deployment
### Network camera configuration
When using the network camera for the first time, first connect the phone to the same Wi-Fi network, and then use the Tenda app to add the camera and complete the network configuration.
```{note}
Ensure that the Quectel Pi M2 smart single-board computer and the network camera are on the same local area network; otherwise, the camera's RTSP video stream cannot be retrieved.
```
### Obtain project code
1. Open a terminal and run the following commands to install Git and clone the project code:
```shell
sudo apt update
sudo apt install -y git
git clone https://github.com/Quectel-Pi/demo-people-counting-device.git
```
2. Set directory permissions:
```shell
sudo chmod -R 755 ~/demo-people-counting-device
```
3. Install project dependencies:
```shell
pip install --upgrade pip
cd demo-people-counting-device
pip install -r requirements.txt
```
### Camera parameter configuration (optional)
```{note}
The IP address of the network camera can be obtained from the device information page in the Tenda app.
```
On the Quectel Pi M2 smart single-board computer, open the Firefox browser and enter the "IP address of the webcam". Use the default username: **admin** and password: **admin123456** to enter the backend and set the video encoding type to H.264 and the audio encoding type to AAC.
### Launch application
Enter the project source code directory and run the corresponding script:
```shell
cd demo-people-counting-device/src
# Run IP camera version
python3 ip_camera_main.py
# Or run USB camera version
python3 usb_camera_main.py
# Or run local video test version
python3 local_video_main.py --video ../assets/street.mp4
--video: Specify the video file path (required)
--model: Specify the YOLO model path (optional; defaults to yolov8n.pt)
```
# Application demo
Your browser does not support the video tag.
people-counting-device
# Common troubleshooting
## Q1: Camera cannot be opened
**Solution:**
- Add the current user to the video user group: **sudo usermod -aG video $USER**.
- Restart the system to apply group permissions.
- Check if the camera is occupied by another process.
## Q2: Model file loading failed
**Solution:**
- Ensure scripts are run from the *src/* directory (all model files are located in this directory).
- Do not change the working directory; execute startup commands directly in the *src/* directory.
## Q3: IP camera connection failed
**Solution:**
- Test network connectivity: ping .
- Confirm that the camera's ONVIF service is enabled.
## Q4: System performance lag
**Solution:**
- Disable ReID feature before launch: `export BYTETRACK_USE_REID=0` (or `BYTETRACK_USE_REID=0 python3 ...`).
- Reduce display window resolution.
# Technical support and contributions
If you encounter any issues during use, please submit technical inquiries on the [Quectel Official Forum](). Our technical support team will respond promptly.
Project open-source repository: [https://github.com/Quectel-Pi/demo-people-counting-device]()
Welcome to submit an issue to report a problem or a pull request to improve the code.